<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        
        <title>
            
    
                Deprecated Event Interfaces
             &mdash; 
    SQLAlchemy 0.8 Documentation

        </title>
        
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/docs.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '../',
          VERSION:     '0.8.2',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>
        <script type="text/javascript" src="../_static/jquery.js"></script>
        <script type="text/javascript" src="../_static/underscore.js"></script>
        <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/init.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
        <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="top" title="SQLAlchemy 0.8 Documentation" href="../index.html" />
        <link rel="up" title="SQLAlchemy Core" href="index.html" />
        <link rel="next" title="Core Exceptions" href="exceptions.html" />
        <link rel="prev" title="Expression Serializer Extension" href="serializer.html" />

    </head>
    <body>
        










<div id="docs-container">



<div id="docs-header">
    <h1>SQLAlchemy 0.8 Documentation</h1>

    <div id="docs-search">
    Search:
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>

    <div id="docs-version-header">
        Release: <span class="version-num">0.8.2</span> | Release Date: July 3, 2013


    </div>

</div>

<div id="docs-top-navigation">
    <div id="docs-top-page-control" class="docs-navigation-links">
        <ul>
            <li>Prev:
            <a href="serializer.html" title="previous chapter">Expression Serializer Extension</a>
            </li>
            <li>Next:
            <a href="exceptions.html" title="next chapter">Core Exceptions</a>
            </li>

        <li>
            <a href="../contents.html">Table of Contents</a> |
            <a href="../genindex.html">Index</a>
            | <a href="../_sources/core/interfaces.txt">view source
        </li>
        </ul>
    </div>

    <div id="docs-navigation-banner">
        <a href="../index.html">SQLAlchemy 0.8 Documentation</a>
                » <a href="index.html" title="SQLAlchemy Core">SQLAlchemy Core</a>
        » 
                Deprecated Event Interfaces
             

        <h2>
            
                Deprecated Event Interfaces
            
        </h2>
    </div>

</div>

<div id="docs-body-container">

    <div id="docs-sidebar">
    <h3><a href="../index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">Deprecated Event Interfaces</a><ul>
<li><a class="reference internal" href="#execution-connection-and-cursor-events">Execution, Connection and Cursor Events</a></li>
<li><a class="reference internal" href="#connection-pool-events">Connection Pool Events</a></li>
</ul>
</li>
</ul>


    <h4>Previous Topic</h4>
    <p>
    <a href="serializer.html" title="previous chapter">Expression Serializer Extension</a>
    </p>
    <h4>Next Topic</h4>
    <p>
    <a href="exceptions.html" title="next chapter">Core Exceptions</a>
    </p>


    <h4>Quick Search</h4>
    <p>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </p>

    </div>

    <div id="docs-body" class="withsidebar" >
        
<div class="section" id="module-sqlalchemy.interfaces">
<span id="deprecated-event-interfaces"></span><span id="dep-interfaces-core-toplevel"></span><h1>Deprecated Event Interfaces<a class="headerlink" href="#module-sqlalchemy.interfaces" title="Permalink to this headline">¶</a></h1>
<p>This section describes the class-based core event interface introduced in
SQLAlchemy 0.5.  The ORM analogue is described at <a class="reference internal" href="../orm/deprecated.html"><em>Deprecated ORM Event Interfaces</em></a>.</p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 0.7: </span>The new event system described in <a class="reference internal" href="event.html"><em>Events</em></a> replaces
the extension/proxy/listener system, providing a consistent interface
to all events without the need for subclassing.</p>
<div class="section" id="execution-connection-and-cursor-events">
<h2>Execution, Connection and Cursor Events<a class="headerlink" href="#execution-connection-and-cursor-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.interfaces.ConnectionProxy">
<em class="property">class </em><tt class="descclassname">sqlalchemy.interfaces.</tt><tt class="descname">ConnectionProxy</tt><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy" title="Permalink to this definition">¶</a></dt>
<dd><p>Allows interception of statement execution by Connections.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.interfaces.ConnectionProxy" title="sqlalchemy.interfaces.ConnectionProxy"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionProxy</span></tt></a> is deprecated.   Please
refer to <a class="reference internal" href="events.html#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionEvents</span></tt></a>.</p>
</div>
<p>Either or both of the <tt class="docutils literal"><span class="pre">execute()</span></tt> and <tt class="docutils literal"><span class="pre">cursor_execute()</span></tt>
may be implemented to intercept compiled statement and
cursor level executions, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyProxy</span><span class="p">(</span><span class="n">ConnectionProxy</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">execute</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">conn</span><span class="p">,</span> <span class="n">execute</span><span class="p">,</span> <span class="n">clauseelement</span><span class="p">,</span>
                <span class="o">*</span><span class="n">multiparams</span><span class="p">,</span> <span class="o">**</span><span class="n">params</span><span class="p">):</span>
        <span class="k">print</span> <span class="s">&quot;compiled statement:&quot;</span><span class="p">,</span> <span class="n">clauseelement</span>
        <span class="k">return</span> <span class="n">execute</span><span class="p">(</span><span class="n">clauseelement</span><span class="p">,</span> <span class="o">*</span><span class="n">multiparams</span><span class="p">,</span> <span class="o">**</span><span class="n">params</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">cursor_execute</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">execute</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span>
                       <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
        <span class="k">print</span> <span class="s">&quot;raw statement:&quot;</span><span class="p">,</span> <span class="n">statement</span>
        <span class="k">return</span> <span class="n">execute</span><span class="p">(</span><span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">)</span></pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">execute</span></tt> argument is a function that will fulfill the default
execution behavior for the operation.  The signature illustrated
in the example should be used.</p>
<p>The proxy is installed into an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> via
the <tt class="docutils literal"><span class="pre">proxy</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">e</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">&#39;someurl://&#39;</span><span class="p">,</span> <span class="n">proxy</span><span class="o">=</span><span class="n">MyProxy</span><span class="p">())</span></pre></div>
</div>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.begin">
<tt class="descname">begin</tt><big>(</big><em>conn</em>, <em>begin</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.begin" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.begin_twophase">
<tt class="descname">begin_twophase</tt><big>(</big><em>conn</em>, <em>begin_twophase</em>, <em>xid</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.begin_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin_twophase() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.commit">
<tt class="descname">commit</tt><big>(</big><em>conn</em>, <em>commit</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.commit" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.commit_twophase">
<tt class="descname">commit_twophase</tt><big>(</big><em>conn</em>, <em>commit_twophase</em>, <em>xid</em>, <em>is_prepared</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.commit_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit_twophase() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.cursor_execute">
<tt class="descname">cursor_execute</tt><big>(</big><em>execute</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>executemany</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.cursor_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept low-level cursor execute() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.execute">
<tt class="descname">execute</tt><big>(</big><em>conn</em>, <em>execute</em>, <em>clauseelement</em>, <em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept high level execute() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.prepare_twophase">
<tt class="descname">prepare_twophase</tt><big>(</big><em>conn</em>, <em>prepare_twophase</em>, <em>xid</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.prepare_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept prepare_twophase() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.release_savepoint">
<tt class="descname">release_savepoint</tt><big>(</big><em>conn</em>, <em>release_savepoint</em>, <em>name</em>, <em>context</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.release_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept release_savepoint() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.rollback">
<tt class="descname">rollback</tt><big>(</big><em>conn</em>, <em>rollback</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.rollback" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.rollback_savepoint">
<tt class="descname">rollback_savepoint</tt><big>(</big><em>conn</em>, <em>rollback_savepoint</em>, <em>name</em>, <em>context</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.rollback_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_savepoint() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.rollback_twophase">
<tt class="descname">rollback_twophase</tt><big>(</big><em>conn</em>, <em>rollback_twophase</em>, <em>xid</em>, <em>is_prepared</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.rollback_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_twophase() events.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.savepoint">
<tt class="descname">savepoint</tt><big>(</big><em>conn</em>, <em>savepoint</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept savepoint() events.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="connection-pool-events">
<h2>Connection Pool Events<a class="headerlink" href="#connection-pool-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.interfaces.PoolListener">
<em class="property">class </em><tt class="descclassname">sqlalchemy.interfaces.</tt><tt class="descname">PoolListener</tt><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener" title="Permalink to this definition">¶</a></dt>
<dd><p>Hooks into the lifecycle of connections in a <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.interfaces.PoolListener" title="sqlalchemy.interfaces.PoolListener"><tt class="xref py py-class docutils literal"><span class="pre">PoolListener</span></tt></a> is deprecated.   Please
refer to <a class="reference internal" href="events.html#sqlalchemy.events.PoolEvents" title="sqlalchemy.events.PoolEvents"><tt class="xref py py-class docutils literal"><span class="pre">PoolEvents</span></tt></a>.</p>
</div>
<p>Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyListener</span><span class="p">(</span><span class="n">PoolListener</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">connect</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dbapi_con</span><span class="p">,</span> <span class="n">con_record</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;perform connect operations&#39;&#39;&#39;</span>
    <span class="c"># etc.</span>

<span class="c"># create a new pool with a listener</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">QueuePool</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">listeners</span><span class="o">=</span><span class="p">[</span><span class="n">MyListener</span><span class="p">()])</span>

<span class="c"># add a listener after the fact</span>
<span class="n">p</span><span class="o">.</span><span class="n">add_listener</span><span class="p">(</span><span class="n">MyListener</span><span class="p">())</span>

<span class="c"># usage with create_engine()</span>
<span class="n">e</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">&quot;url://&quot;</span><span class="p">,</span> <span class="n">listeners</span><span class="o">=</span><span class="p">[</span><span class="n">MyListener</span><span class="p">()])</span></pre></div>
</div>
<p>All of the standard connection <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> types can
accept event listeners for key connection lifecycle events:
creation, pool check-out and check-in.  There are no events fired
when a connection closes.</p>
<p>For any given DB-API connection, there will be one <tt class="docutils literal"><span class="pre">connect</span></tt>
event, <cite>n</cite> number of <tt class="docutils literal"><span class="pre">checkout</span></tt> events, and either <cite>n</cite> or <cite>n - 1</cite>
<tt class="docutils literal"><span class="pre">checkin</span></tt> events.  (If a <tt class="docutils literal"><span class="pre">Connection</span></tt> is detached from its
pool via the <tt class="docutils literal"><span class="pre">detach()</span></tt> method, it won&#8217;t be checked back in.)</p>
<p>These are low-level events for low-level objects: raw Python
DB-API connections, without the conveniences of the SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper, <tt class="docutils literal"><span class="pre">Dialect</span></tt> services or <tt class="docutils literal"><span class="pre">ClauseElement</span></tt>
execution.  If you execute SQL through the connection, explicitly
closing all cursors and other resources is recommended.</p>
<p>Events also receive a <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt>, a long-lived internal
<tt class="docutils literal"><span class="pre">Pool</span></tt> object that basically represents a &#8220;slot&#8221; in the
connection pool.  <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> objects have one public
attribute of note: <tt class="docutils literal"><span class="pre">info</span></tt>, a dictionary whose contents are
scoped to the lifetime of the DB-API connection managed by the
record.  You can use this shared storage area however you like.</p>
<p>There is no need to subclass <tt class="docutils literal"><span class="pre">PoolListener</span></tt> to handle events.
Any class that implements one or more of these methods can be used
as a pool listener.  The <tt class="docutils literal"><span class="pre">Pool</span></tt> will inspect the methods
provided by a listener object and add the listener to one or more
internal event queues based on its capabilities.  In terms of
efficiency and function call overhead, you&#8217;re much better off only
providing implementations for the hooks you&#8217;ll be using.</p>
<dl class="method">
<dt id="sqlalchemy.interfaces.PoolListener.checkin">
<tt class="descname">checkin</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener.checkin" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection returns to the pool.</p>
<p>Note that the connection may be closed, and may be None if the
connection has been invalidated.  <tt class="docutils literal"><span class="pre">checkin</span></tt> will not be called
for detached connections.  (They do not return to the pool.)</p>
<dl class="docutils">
<dt>dbapi_con</dt>
<dd>A raw DB-API connection</dd>
<dt>con_record</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</dd>
</dl>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.PoolListener.checkout">
<tt class="descname">checkout</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em>, <em>con_proxy</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener.checkout" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection is retrieved from the Pool.</p>
<dl class="docutils">
<dt>dbapi_con</dt>
<dd>A raw DB-API connection</dd>
<dt>con_record</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</dd>
<dt>con_proxy</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionFairy</span></tt> which manages the connection for the span of
the current checkout.</dd>
</dl>
<p>If you raise an <tt class="docutils literal"><span class="pre">exc.DisconnectionError</span></tt>, the current
connection will be disposed and a fresh connection retrieved.
Processing of all checkout listeners will abort and restart
using the new connection.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.PoolListener.connect">
<tt class="descname">connect</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called once for each new DB-API connection or Pool&#8217;s <tt class="docutils literal"><span class="pre">creator()</span></tt>.</p>
<dl class="docutils">
<dt>dbapi_con</dt>
<dd>A newly connected raw DB-API connection (not a SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper).</dd>
<dt>con_record</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</dd>
</dl>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.interfaces.PoolListener.first_connect">
<tt class="descname">first_connect</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener.first_connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called exactly once for the first DB-API connection.</p>
<dl class="docutils">
<dt>dbapi_con</dt>
<dd>A newly connected raw DB-API connection (not a SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper).</dd>
<dt>con_record</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</dd>
</dl>
</dd></dl>

</dd></dl>

</div>
</div>

    </div>

</div>

<div id="docs-bottom-navigation" class="docs-navigation-links">
        Previous:
        <a href="serializer.html" title="previous chapter">Expression Serializer Extension</a>
        Next:
        <a href="exceptions.html" title="next chapter">Core Exceptions</a>

    <div id="docs-copyright">
        &copy; <a href="../copyright.html">Copyright</a> 2007-2013, the SQLAlchemy authors and contributors.
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
    </div>
</div>

</div>

        
    </body>
</html>


